Getting Started topic

This topic will guide you through the process of setting up Werkbank for your Flutter project. You should already be familiar what Werkbank is and the purpose of use cases from the Welcome topic.

Table of Contents

• Creating the Werkbank Flutter Project
• WerkbankApp Setup
  • Defining the Use Case Tree
• Creating UseCases
• Next Steps

Creating the Werkbank Flutter Project

To create a Werkbank for your project, start by creating a new Flutter app. A good place to put this app would be next to the folder of your project. For example, you can do this by running

flutter create --platforms=windows,linux,macos,web my_project_werkbank

in the folder where your my_project Flutter app folder is located. It is recommended to only add platforms with desktop support because Werkbank is optimized for desktop interfaces rather than mobile screens.

Once the Flutter project is generated, add werkbank as a dependency to your project:

cd my_project_werkbank
flutter pub add werkbank

You will also need to add a dependency to your flutter package or app where the widgets you want to showcase are located.

Tip

The following sections introduce you to a very basic setup of a Werkbank app. Check out the example project at https://github.com/neusta-mobile-solutions-gmbh/werkbank/tree/main/example/example_werkbank for a more elaborate setup that will help you get the most out of Werkbank.

WerkbankApp Setup

Set up the main.dart file to run a StatelessWidget that builds a WerkbankApp widget.

// ---- lib/main.dart ---- //

import 'package:my_project_werkbank/root.dart';
import 'package:flutter/material.dart';
import 'package:werkbank/werkbank.dart';

void main() {
  runApp(const MyProjectWerkbankApp());
}

class MyProjectWerkbankApp extends StatelessWidget {
  const MyProjectWerkbankApp({super.key});

  @override
  Widget build(BuildContext context) {
    return WerkbankApp(
      name: 'My Project Werkbank',
      logo: const FlutterLogo(),
      appConfig: AppConfig.material(),
      addonConfig: AddonConfig(
        addons: [
          // Add more addons like the ThemingAddon or LocalizationAddon.
        ],
      ),
      // The root of your use case tree.
      root: root,
    );
  }
}

Important

Do not pass the WerkbankApp directly to runApp, as this will prevent hot reload from updating the use cases, addons and more when you change them.

The name and logo will be displayed in the top left corner of the WerkbankApp. They should represent the name and logo of your project. The logo can also be set to null if you don't have one.

The appConfig parameter accepts an AppConfig object that defines how your use cases will be wrapped with a MaterialApp, CupertinoApp, or WidgetsApp. Depending on the design system of your project, you can use

• AppConfig.material() for Material Design,
• AppConfig.cupertino() for Cupertino,
• AppConfig.widgets() for a minimal app,
• or the raw AppConfig() constructor for a custom app.

The addonConfig parameter is used to configure addons that provide most of the functionality in Werkbank using an AddonConfig object. By default, it already includes several addons. Its addons parameter allows you to add additional addons or reconfigure the implicitly included default addons. For example, you should consider adding the ThemingAddon and the LocalizationAddon, since almost every app uses theming, and it is also good practice to use a localization framework even if your app only supports one language. To learn more about addons, visit the Configuring Addons topic.

Defining the Use Case Tree

The root parameter expects a WerkbankRoot instance with children that form a hierarchy of your use cases.

// ---- lib/root.dart ---- //

import 'package:my_project_werkbank/example_use_cases.dart';
import 'package:werkbank/werkbank.dart';

WerkbankRoot get root => WerkbankRoot(
      children: [
        exampleUseCase,
        WerkbankFolder(
          name: 'Example Folder',
          children: [
            anotherUseCase,
            yetAnotherUseCase,
          ],
        ),
      ],
    );

The WerkbankRoot defines the root of a tree with all your use cases. Use cases are defined in the tree using WerkbankUseCase. You can nest use cases inside WerkbankFolder or WerkbankComponent nodes to group them logically. The difference between these two is:

• WerkbankComponents are intended to be used to group multiple use cases that display the same component/widget, just in different ways.
• WerkbankComponent has a different icon in the navigation tree than folders.
• WerkbankFolder is sorted to the top among its siblings, unlike WerkbankComponents, which are sorted exactly like use cases.

Creating UseCases

You can define a use case by creating a getter for a WerkbankUseCase instance with a name and a builder.

// ---- lib/example_use_cases.dart ---- //

import 'package:werkbank/werkbank.dart';

WerkbankUseCase get exampleUseCase => WerkbankUseCase(
  name: 'Example Use Case',
  builder: _exampleUseCase,
);

WidgetBuilder _exampleUseCase(UseCaseComposer c) {
  // You can do many things with the composer here.
  return (context) {
    return ExampleWidget();
  };
}

Important

Always define your WerkbankRoot, WerkbankFolders, WerkbankComponents, and WerkbankUseCases as a getter or function, not as a const or final top-level variable. Otherwise, a hot reload will not update them when you make changes.

A UseCaseBuilder is defined by a function that takes a UseCaseComposer and returns a WidgetBuilder. In turn, the WidgetBuilder then returns the widget that the use case is supposed to showcase.

The UseCaseComposer can be used in many different ways to configure and augment the use case. Visit the Writing Use Cases topic to learn more about how to expertly write use cases and utilize the UseCaseComposer to its full potential.

Now you should have everything set up to run your Werkbank app.

Tip

Check out the "Shortcuts" section in the home page of your running Werkbank app to learn the basic keyboard shortcuts.

Next Steps

Take a look at these topics next to advance your Werkbank setup further:

• File Structure - Learn how to organize the files and use cases in your project.
• Configuring Addons - Further configure the addons you are using.
• Writing Use Cases - Explore how to augment your use cases by utilizing the UseCaseComposer.

Classes

AddonConfig

A class that defines which addons are used. This needs to be passed to a WerkbankApp or DisplayApp. If you are using both, make sure to pass the same AddonConfig in order to ensure consistent behavior.

AppConfig

A class that defines how to build the app widget, which is typically one of MaterialApp, CupertinoApp, or WidgetsApp.

WerkbankApp

The main entry point for a Werkbank.

WerkbankComponent

A WerkbankNode that defines a collection of WerkbankUseCases. This is typically used when there are multiple use cases for a single component, such as a button or a switch.

WerkbankFolder

A WerkbankNode that defines a collection of WerkbankNodes.

WerkbankRoot

A WerkbankNode that defines a collection of WerkbankChildNodes.

WerkbankUseCase

A WerkbankNode that defines a single use case.

Typedefs

UseCaseBuilder = WidgetBuilder Function(UseCaseComposer c)

A builder function for a use case.

UseCaseParentBuilder = void Function(UseCaseComposer c)

A function too manipulate the UseCaseComposer like it would be done at the beginning of a UseCaseBuilder definition.